Программный интерфейс (API)

Форматы API

• JSONRPC2.0 по Websocket
• RPC-like по HTTP
• RPC-like по CLI

API-функции сервисов

• Server

Пример использования API

Форматы API

Пульт.Онлайн предоставляет API для большинства отдельных сервисов, входящих в состав системы.

API предоставляется в следующих форматах:

• JSONRPC2.0 по Websocket
• RPC-like по HTTP (только для сервиса server)
• RPC-like по CLI (Интерфейс командной строки)

Запросы ко всем сервисам, кроме сервиса server, не требуют аутентификации. Большинство запросов к сервису server по HTTP и WS требуют аутентификации с помощью API-ключа. Чтобы получить API-ключ, заведите пользователя с требуемыми правами и сгенерируйте в настройках его профиля API-ключ. API-ключ передается параметром pult_apikey.

JSONRPC2.0 по Websocket

Порт, на котором сервис принимает API-запросы, указан в его настройках в параметре tcp_port. Данный порт должен быть открыт в фаерволе. Необходимо также убедиться что у сервиса включен параметр listen_tcp_port, а параметр allowed_ip позволяет подключаться с IP клиента.

Формат запроса:

{
    "jsonrpc":"2.0",
    "id":1,
    "method":"<method>",
    "params":{
        "param1":<value1>,
        "paramN":<valueN>,
    }
}

Пример запроса

Для тестовых запросов можно воспользоваться плагином для браузера, например Smart Websocket Client или Advanced Websocket Client. В строке Websocket address необходимо указать URL сервиса, включая хост и порт, например:

wss://192.168.0.100:11200/

Запрос:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "set",
    "params": {
        "var": "P1_N1_var1",
        "value": 123.456789,
    }
}

Ответ:

{
    "jsonrpc": "2.0",
    "id": "1",
    "result": true
}

RPC-like по HTTP

http(s)://<server_host>/api/<method>?<param1>=<value1>&<paramN>=<valueN>

Для передачи JSON в параметре предварите имя параметра символом @

Пример запроса

Выполним http-запрос к сервису server на демо-сервере webscada.ru c использование API-ключа на установку значения переменной:

https://webscada.ru/api/var_set?pult_apikey=31269DCE4F983A31FBE8B88DF67CDAE2&var=P6_N6_temp_setpoint&value=25

Ответ:

true

RPC-like по CLI

cd /pult_server
./cli unix://<unix_socket> <method> [<param1>=<value1> <paramN>=<valueN>]

Для вывода в виде JSON вместо псевдо-кода предварите имя метода символом @
Для передачи JSON в параметре предварите имя параметра символом @

Пример запроса

Перейдем в рабочую папку сервера

cd /pult_server

и отправим команду сервису server на получение списка узлов по префиксам:

./cli unix://server.us @node_list @prefixes=["P1_N1"] pult_apikey=D798B3DE1C798AABC3E5E1C5EDE7FF79

Ответ:

{"result":{"keys":["title","id","prefix","index","path","gateway","params","tags","icon"],"rows":[["Узел1",1,"P1_N1",0,"/projects/Проект1.project/nodes/Узел1.node",{},{"host":"192.168.0.13","port":502,"keepalive":1,"sharecon":1,"async":0,"slave":1,"offset":0,"timeout":300,"period":1000,"grouping":"1","delay":0,"writecmd":"16","metric_period":10000,"ignore_errors":0},{}]]}}